建立 Git 子倉庫
目標： 在 A 專案中建立 B 專案，並將 B 專案作為獨立倉庫，透過 git submodule 的方式引入到 A 專案中。
一、為什麼使用子倉庫（submodule）
使用 git submodule 的核心原因是：
- B 專案可以獨立開發、獨立發佈
- A 專案只引用 B 的某個確定版本
- 多個專案可以複用同一個 B
- 避免把所有程式碼都塞進一個倉庫（假 monorepo）
適合場景：
- SDK / 工具庫
- 基礎元件
- 需要獨立 CI / release 的模組
二、整體流程概覽
- 在 A 專案中建立 B 專案目錄
- 初始化 B 專案為獨立 Git 倉庫
- 使用
gh建立遠端倉庫並推送 - 將 B 專案作為 submodule 新增回 A 專案
- 提交 A 專案的 submodule 變更
三、在 A 專案中建立 B 專案
進入 A 專案根目錄：
cd A-project
建立 B 專案目錄（示例）：
mkdir -p packages/B-project
cd packages/B-project
四、初始化 B 專案倉庫
1. 初始化 Git
git init
2. 建立初始提交（必須）
echo "# B-project" > README.md
git add .
git commit -m "chore: initial commit"
⚠️ submodule 不能引用一個沒有 commit 的倉庫
五、使用 GitHub CLI 建立遠端倉庫
確保已登入 GitHub：
gh auth status
建立並推送倉庫（fish / bash 通用寫法）：
gh repo create B-project --private --source=. --remote=origin --push
如果是 public 倉庫，將
--private改為--public
驗證遠端倉庫：
git remote -v
六、將 B 專案作為子倉庫加入 A 專案
1. 回到 A 專案根目錄
cd ../../
2. 刪除本機 B 目錄（關鍵步驟）
rm -rf packages/B-project
⚠️ submodule 會自行 clone 倉庫，本機目錄必須為空
3. 新增 submodule
git submodule add https://github.com/<使用者名稱或組織>/B-project.git packages/B-project
成功後會產生：
packages/B-project/.gitmodules
七、提交 A 專案的 submodule 變更
git add .gitmodules packages/B-project
git commit -m "chore: add B-project as submodule"
git push
八、日常開發與更新流程
1. 開發 B 專案
cd packages/B-project
git checkout main
修改並提交：
git add .
git commit -m "feat: xxx"
git push
2. 在 A 專案中更新子倉庫版本
cd ../../
git status
會看到：
modified: packages/B-project (new commits)
提交更新：
git add packages/B-project
git commit -m "chore: bump B-project submodule"
git push
九、Clone 含 submodule 的專案
推薦方式（一次性）
git clone --recurse-submodules <A-project-repo>
已 clone 專案補拉子倉庫
git submodule update --init --recursive
十、常見坑總結
❌ 忘記給 B 專案做初始 commit
→ submodule 無法新增
❌ 沒刪除本機目錄就 add submodule
→ already exists and is not a git repository
❌ 更新了 B，卻沒提交 A 的 submodule 指標
→ 其他人拉不到最新版本
十一、補充建議
- 統一子倉庫放在
packages/或libs/目錄 - submodule 更新必須有單獨 commit
- 團隊中約定：禁止直接修改 submodule 的 detached HEAD
結論： submodule 管理的是「依賴的提交」，不是程式碼本身。 想清楚「誰負責發佈，誰負責引用」，就不會踩坑。
如果你願意，我也可以幫你把這篇筆記改成：
- 團隊規範版
- README 精簡版
- 帶流程圖的版本